home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2005 October / PCWOCT05.iso / Software / FromTheMag / XAMPP 1.4.14 / xampp-win32-1.4.14-installer.exe / xampp / php / pear / HTML / Template / Sigma.php < prev   
PHP Script  |  2004-10-01  |  64KB  |  1,731 lines
  1. <?php
  2. //
  3. // +----------------------------------------------------------------------+
  4. // | PHP Version 4                                                        |
  5. // +----------------------------------------------------------------------+
  6. // | Copyright (c) 1997-2003 The PHP Group                                |
  7. // +----------------------------------------------------------------------+
  8. // | This source file is subject to version 2.02 of the PHP license,      |
  9. // | that is bundled with this package in the file LICENSE, and is        |
  10. // | available at through the world-wide-web at                           |
  11. // | http://www.php.net/license/2_02.txt.                                 |
  12. // | If you did not receive a copy of the PHP license and are unable to   |
  13. // | obtain it through the world-wide-web, please send a note to          |
  14. // | license@php.net so we can mail you a copy immediately.               |
  15. // +----------------------------------------------------------------------+
  16. // | Authors: Ulf Wendel <ulf.wendel@phpdoc.de>                           |
  17. // |          Alexey Borzov <avb@php.net>                                 |
  18. // +----------------------------------------------------------------------+
  19. //
  20. // $Id: Sigma.php,v 1.11 2004/05/31 14:09:42 avb Exp $
  21. //
  22.  
  23. require_once 'PEAR.php';
  24.  
  25. define('SIGMA_OK',                         1);
  26. define('SIGMA_ERROR',                     -1);
  27. define('SIGMA_TPL_NOT_FOUND',             -2);
  28. define('SIGMA_BLOCK_NOT_FOUND',           -3);
  29. define('SIGMA_BLOCK_DUPLICATE',           -4);
  30. define('SIGMA_CACHE_ERROR',               -5);
  31. define('SIGMA_UNKNOWN_OPTION',            -6);
  32. define('SIGMA_PLACEHOLDER_NOT_FOUND',     -10);
  33. define('SIGMA_PLACEHOLDER_DUPLICATE',     -11);
  34. define('SIGMA_BLOCK_EXISTS',              -12);
  35. define('SIGMA_INVALID_CALLBACK',          -13);
  36.  
  37. /**
  38. * HTML_Template_Sigma: implementation of Integrated Templates API with 
  39. * template 'compilation' added.
  40. *
  41. * The main new feature in Sigma is the template 'compilation'. Consider the
  42. * following: when loading a template file the engine has to parse it using
  43. * regular expressions to find all the blocks and variable placeholders. This
  44. * is a very "expensive" operation and is definitely an overkill to do on 
  45. * every page request: templates seldom change on production websites. This is
  46. * where the cache kicks in: it saves an internal representation of the 
  47. * template structure into a file and this file gets loaded instead of the 
  48. * source one on subsequent requests (unless the source changes, of course).
  49. * 
  50. * While HTML_Template_Sigma inherits PHPLib Template's template syntax, it has
  51. * an API which is easier to understand. When using HTML_Template_PHPLIB, you
  52. * have to explicitly name a source and a target the block gets parsed into.
  53. * This gives maximum flexibility but requires full knowledge of template 
  54. * structure from the programmer.
  55. * 
  56. * Integrated Template on the other hands manages block nesting and parsing 
  57. * itself. The engine knows that inner1 is a child of block2, there's
  58. * no need to tell it about this:
  59. *
  60. * + __global__ (hidden and automatically added)
  61. *     + block1
  62. *     + block2
  63. *         + inner1
  64. *         + inner2
  65. *
  66. * To add content to block1 you simply type:
  67. * <code>$tpl->setCurrentBlock("block1");</code>
  68. * and repeat this as often as needed:
  69. * <code>
  70. *   $tpl->setVariable(...);
  71. *   $tpl->parseCurrentBlock();
  72. * </code>
  73. *
  74. * To add content to block2 you would type something like:
  75. * <code>
  76. * $tpl->setCurrentBlock("inner1");
  77. * $tpl->setVariable(...);
  78. * $tpl->parseCurrentBlock();
  79. *
  80. * $tpl->setVariable(...);
  81. * $tpl->parseCurrentBlock();
  82. *
  83. * $tpl->parse("block2");
  84. * </code>
  85. *
  86. * This will result in one repetition of block2 which contains two repetitions
  87. * of inner1. inner2 will be removed if $removeEmptyBlock is set to true (which 
  88. * is the default).
  89. *
  90. * Usage:
  91. * <code>
  92. * $tpl = new HTML_Template_Sigma( [string filerootdir], [string cacherootdir] );
  93. *
  94. * // load a template or set it with setTemplate()
  95. * $tpl->loadTemplatefile( string filename [, boolean removeUnknownVariables, boolean removeEmptyBlocks] )
  96. *
  97. * // set "global" Variables meaning variables not beeing within a (inner) block
  98. * $tpl->setVariable( string variablename, mixed value );
  99. *
  100. * // like with the HTML_Template_PHPLIB there's a second way to use setVariable()
  101. * $tpl->setVariable( array ( string varname => mixed value ) );
  102. *
  103. * // Let's use any block, even a deeply nested one
  104. * $tpl->setCurrentBlock( string blockname );
  105. *
  106. * // repeat this as often as you need it.
  107. * $tpl->setVariable( array ( string varname => mixed value ) );
  108. * $tpl->parseCurrentBlock();
  109. *
  110. * // get the parsed template or print it: $tpl->show()
  111. * $html = $tpl->get();
  112. * </code>
  113. *
  114. * @author   Ulf Wendel <ulf.wendel@phpdoc.de>
  115. * @author   Alexey Borzov <avb@php.net>
  116. * @version  $Revision: 1.11 $
  117. * @access   public
  118. * @package  HTML_Template_Sigma
  119. */
  120. class HTML_Template_Sigma extends PEAR
  121. {
  122.    /**
  123.     * First character of a variable placeholder ( _{_VARIABLE} ).
  124.     * @var      string
  125.     * @access   public
  126.     * @see      $closingDelimiter, $blocknameRegExp, $variablenameRegExp
  127.     */
  128.     var $openingDelimiter = '{';
  129.  
  130.    /**
  131.     * Last character of a variable placeholder ( {VARIABLE_}_ )
  132.     * @var      string
  133.     * @access   public
  134.     * @see      $openingDelimiter, $blocknameRegExp, $variablenameRegExp
  135.     */
  136.     var $closingDelimiter = '}';
  137.  
  138.    /**
  139.     * RegExp for matching the block names in the template.
  140.     * Per default "sm" is used as the regexp modifier, "i" is missing.
  141.     * That means a case sensitive search is done.
  142.     * @var      string
  143.     * @access   public
  144.     * @see      $variablenameRegExp, $openingDelimiter, $closingDelimiter
  145.     */
  146.     var $blocknameRegExp = '[0-9A-Za-z_-]+';
  147.  
  148.    /**
  149.     * RegExp matching a variable placeholder in the template.
  150.     * Per default "sm" is used as the regexp modifier, "i" is missing.
  151.     * That means a case sensitive search is done.
  152.     * @var      string    
  153.     * @access   public
  154.     * @see      $blocknameRegExp, $openingDelimiter, $closingDelimiter
  155.     */
  156.     var $variablenameRegExp = '[0-9A-Za-z_-]+';
  157.  
  158.    /**
  159.     * RegExp used to find variable placeholder, filled by the constructor
  160.     * @var      string    Looks somewhat like @(delimiter varname delimiter)@
  161.     * @see      HTML_Template_Sigma()
  162.     */
  163.     var $variablesRegExp = '';
  164.  
  165.    /**
  166.     * RegExp used to strip unused variable placeholders
  167.     * @see      $variablesRegExp, HTML_Template_Sigma()
  168.     */
  169.     var $removeVariablesRegExp = '';
  170.  
  171.    /**
  172.     * RegExp used to find blocks and their content, filled by the constructor
  173.     * @var      string
  174.     * @see      HTML_Template_Sigma()
  175.     */
  176.     var $blockRegExp = '';
  177.  
  178.    /**
  179.     * Controls the handling of unknown variables, default is remove
  180.     * @var      boolean
  181.     * @access   public
  182.     */
  183.     var $removeUnknownVariables = true;
  184.  
  185.    /**
  186.     * Controls the handling of empty blocks, default is remove
  187.     * @var      boolean
  188.     * @access   public
  189.     */
  190.     var $removeEmptyBlocks = true;
  191.  
  192.    /**
  193.     * Name of the current block
  194.     * @var      string
  195.     */
  196.     var $currentBlock = '__global__';
  197.  
  198.    /**
  199.     * Template blocks and their content
  200.     * @var      array
  201.     * @see      _buildBlocks()
  202.     * @access   private
  203.     */
  204.     var $_blocks = array();
  205.  
  206.    /**
  207.     * Content of parsed blocks
  208.     * @var      array
  209.     * @see      get(), parse()
  210.     * @access   private
  211.     */
  212.     var $_parsedBlocks = array();
  213.  
  214.    /**
  215.     * Variable names that appear in the block
  216.     * @var      array
  217.     * @see      _buildBlockVariables()
  218.     * @access   private
  219.     */
  220.     var $_blockVariables = array();
  221.  
  222.    /**
  223.     * Inner blocks inside the block
  224.     * @var      array
  225.     * @see      _buildBlocks()
  226.     * @access   private
  227.     */
  228.     var $_children = array();
  229.  
  230.    /**
  231.     * List of blocks to preserve even if they are "empty"
  232.     * @var      array
  233.     * @see      touchBlock(), $removeEmptyBlocks
  234.     * @access   private
  235.     */
  236.     var $_touchedBlocks = array();
  237.  
  238.    /**
  239.     * List of blocks which should not be shown even if not "empty"
  240.     * @var      array
  241.     * @see      hideBlock(), $removeEmptyBlocks
  242.     * @access   private
  243.     */
  244.     var $_hiddenBlocks = array();
  245.  
  246.    /**
  247.     * Variables for substitution.
  248.     *
  249.     * Variables are kept in this array before the replacements are done.
  250.     * This allows automatic removal of empty blocks.
  251.     * 
  252.     * @var      array
  253.     * @see      setVariable()
  254.     * @access   private
  255.     */
  256.     var $_variables = array();
  257.  
  258.    /**
  259.     * Global variables for substitution
  260.     * 
  261.     * These are substituted into all blocks, are not cleared on
  262.     * block parsing and do not trigger "non-empty" logic. I.e. if 
  263.     * only global variables are substituted into the block, it is
  264.     * still considered "empty".
  265.     *
  266.     * @var      array
  267.     * @see      setVariable(), setGlobalVariable()
  268.     * @access   private
  269.     */
  270.     var $_globalVariables = array();
  271.  
  272.    /**
  273.     * Root directory for "source" templates
  274.     * @var    string
  275.     * @see    HTML_Template_Sigma(), setRoot()
  276.     */
  277.     var $fileRoot = '';
  278.  
  279.    /**
  280.     * Directory to store the "prepared" templates in
  281.     * @var      string
  282.     * @see      HTML_Template_Sigma(), setCacheRoot()
  283.     * @access   private
  284.     */
  285.     var $_cacheRoot = null;
  286.  
  287.    /**
  288.     * Flag indicating that the global block was parsed
  289.     * @var    boolean
  290.     */
  291.     var $flagGlobalParsed = false;
  292.  
  293.    /**
  294.     * Options to control some finer aspects of Sigma's work.
  295.     * 
  296.     * $_options['preserve_data'] If false, then substitute variables and remove empty 
  297.     * placeholders in data passed through setVariable (see also bugs #20199, #21951)
  298.     * $_options['trim_on_save'] Whether to trim extra whitespace from template on cache save.
  299.     * Generally safe to have this on, unless you have <pre></pre> in templates or want to 
  300.     * preserve HTML indentantion
  301.     */
  302.     var $_options = array(
  303.         'preserve_data' => false,
  304.         'trim_on_save'  => true
  305.     );
  306.  
  307.    /**
  308.     * Function name prefix used when searching for function calls in the template
  309.     * @var    string
  310.     */
  311.     var $functionPrefix = 'func_';
  312.  
  313.    /**
  314.     * Function name RegExp
  315.     * @var    string
  316.     */
  317.     var $functionnameRegExp = '[_a-zA-Z]+[A-Za-z_0-9]*';
  318.  
  319.    /**
  320.     * RegExp used to grep function calls in the template (set by the constructor)
  321.     * @var    string
  322.     * @see    _buildFunctionlist(), HTML_Template_Sigma()
  323.     */
  324.     var $functionRegExp = '';
  325.  
  326.    /**
  327.     * List of functions found in the template.
  328.     * @var    array
  329.     * @access private
  330.     */
  331.     var $_functions = array();
  332.  
  333.    /**
  334.     * List of callback functions specified by the user
  335.     * @var    array
  336.     * @access private
  337.     */
  338.     var $_callback = array();
  339.  
  340.    /**
  341.     * RegExp used to find file inclusion calls in the template (should have 'e' modifier)
  342.     * @var  string
  343.     */
  344.     var $includeRegExp = '#<!--\s+INCLUDE\s+(\S+)\s+-->#ime';
  345.  
  346.    /**
  347.     * Files queued for inclusion
  348.     * @var    array
  349.     * @access private
  350.     */
  351.     var $_triggers = array();
  352.  
  353.  
  354.    /**
  355.     * Constructor: builds some complex regular expressions and optionally 
  356.     * sets the root directories.
  357.     *
  358.     * Make sure that you call this constructor if you derive your template
  359.     * class from this one.
  360.     *
  361.     * @param string  root directory for templates
  362.     * @param string  directory to cache "prepared" templates in
  363.     * @see   setRoot(), setCacheRoot()
  364.     */
  365.     function HTML_Template_Sigma($root = '', $cacheRoot = '')
  366.     {
  367.         // the class is inherited from PEAR to be able to use $this->setErrorHandling()
  368.         $this->PEAR();
  369.         $this->variablesRegExp       = '@' . $this->openingDelimiter . '(' . $this->variablenameRegExp . ')' .
  370.                                        '(:(' . $this->functionnameRegExp . '))?' . $this->closingDelimiter . '@sm';
  371.         $this->removeVariablesRegExp = '@'.$this->openingDelimiter.'\s*('.$this->variablenameRegExp.')\s*'.$this->closingDelimiter.'@sm';
  372.         $this->blockRegExp           = '@<!--\s+BEGIN\s+('.$this->blocknameRegExp.')\s+-->(.*)<!--\s+END\s+\1\s+-->@sm';
  373.         $this->functionRegExp        = '@' . $this->functionPrefix . '(' . $this->functionnameRegExp . ')\s*\(@sm';
  374.         $this->setRoot($root);
  375.         $this->setCacheRoot($cacheRoot);
  376.  
  377.         $this->setCallbackFunction('h', 'htmlspecialchars');
  378.         $this->setCallbackFunction('u', 'urlencode');
  379.         $this->setCallbackFunction('j', array(&$this, '_jsEscape'));
  380.     }
  381.  
  382.  
  383.    /**
  384.     * Sets the file root for templates. The file root gets prefixed to all 
  385.     * filenames passed to the object.
  386.     * 
  387.     * @param    string  directory name
  388.     * @see      HTML_Template_Sigma()
  389.     * @access   public
  390.     */
  391.     function setRoot($root)
  392.     {
  393.         if (('' != $root) && ('/' != substr($root, -1))) {
  394.             $root .= '/';
  395.         }
  396.         $this->fileRoot = $root;
  397.     }
  398.  
  399.  
  400.    /**
  401.     * Sets the directory to cache "prepared" templates in, the directory should be writable for PHP.
  402.     * 
  403.     * The "prepared" template contains an internal representation of template 
  404.     * structure: essentially a serialized array of $_blocks, $_blockVariables, 
  405.     * $_children and $_functions, may also contain $_triggers. This allows 
  406.     * to bypass expensive calls to _buildBlockVariables() and especially 
  407.     * _buildBlocks() when reading the "prepared" template instead of 
  408.     * the "source" one.
  409.     * 
  410.     * The files in this cache do not have any TTL and are regenerated when the
  411.     * source templates change.
  412.     * 
  413.     * @param    string  directory name
  414.     * @see      HTML_Template_Sigma(), _getCached(), _writeCache()
  415.     * @access   public
  416.     */
  417.     function setCacheRoot($root)
  418.     {
  419.         if (empty($root)) {
  420.             return true;
  421.         } elseif (('' != $root) && ('/' != substr($root, -1))) {
  422.             $root .= '/';
  423.         }
  424.         $this->_cacheRoot = $root;
  425.     }
  426.  
  427.  
  428.    /**
  429.     * Sets the option for the template class
  430.     * 
  431.     * @access public
  432.     * @param  string  option name
  433.     * @param  mixed   option value
  434.     * @return mixed   SIGMA_OK on success, error object on failure
  435.     */
  436.     function setOption($option, $value)
  437.     {
  438.         if (isset($this->_options[$option])) {
  439.             $this->_options[$option] = $value;
  440.             return SIGMA_OK;
  441.         }
  442.         return $this->raiseError($this->errorMessage(SIGMA_UNKNOWN_OPTION, $option), SIGMA_UNKNOWN_OPTION);
  443.     }
  444.  
  445.  
  446.    /**
  447.     * Returns a textual error message for an error code
  448.     *  
  449.     * @access public
  450.     * @param  integer  error code
  451.     * @param  string   additional data to insert into message
  452.     * @return string   error message
  453.     */
  454.     function errorMessage($code, $data = null)
  455.     {
  456.         static $errorMessages;
  457.         if (!isset($errorMessages)) {
  458.             $errorMessages = array(
  459.                 SIGMA_ERROR                 => 'unknown error',
  460.                 SIGMA_OK                    => '',
  461.                 SIGMA_TPL_NOT_FOUND         => 'Cannot read the template file \'%s\'',
  462.                 SIGMA_BLOCK_NOT_FOUND       => 'Cannot find block \'%s\'',
  463.                 SIGMA_BLOCK_DUPLICATE       => 'The name of a block must be unique within a template. Block \'%s\' found twice.',
  464.                 SIGMA_CACHE_ERROR           => 'Cannot save template file \'%s\'',
  465.                 SIGMA_UNKNOWN_OPTION        => 'Unknown option \'%s\'',
  466.                 SIGMA_PLACEHOLDER_NOT_FOUND => 'Variable placeholder \'%s\' not found',
  467.                 SIGMA_PLACEHOLDER_DUPLICATE => 'Placeholder \'%s\' should be unique, found in multiple blocks',
  468.                 SIGMA_BLOCK_EXISTS          => 'Block \'%s\' already exists',
  469.                 SIGMA_INVALID_CALLBACK      => 'Callback does not exist'
  470.             );
  471.         }
  472.  
  473.         if (PEAR::isError($code)) {
  474.             $code = $code->getCode();
  475.         }
  476.         if (!isset($errorMessages[$code])) {
  477.             return $errorMessages[SIGMA_ERROR];
  478.         } else {
  479.             return (null === $data)? $errorMessages[$code]: sprintf($errorMessages[$code], $data);
  480.         }
  481.     }
  482.  
  483.  
  484.    /**
  485.     * Prints a block with all replacements done.
  486.     * 
  487.     * @access  public
  488.     * @param   string  block name
  489.     * @see     get()
  490.     */
  491.     function show($block = '__global__')
  492.     {
  493.         print $this->get($block);
  494.     }
  495.  
  496.  
  497.    /**
  498.     * Returns a block with all replacements done.
  499.     * 
  500.     * @param    string     block name
  501.     * @param    bool       whether to clear parsed block contents
  502.     * @return   string     block with all replacements done
  503.     * @throws   PEAR_Error
  504.     * @access   public
  505.     * @see      show()
  506.     */
  507.     function get($block = '__global__', $clear = false)
  508.     {
  509.         if (!isset($this->_blocks[$block])) {
  510.             return $this->raiseError($this->errorMessage(SIGMA_BLOCK_NOT_FOUND, $block), SIGMA_BLOCK_NOT_FOUND);
  511.         }
  512.         if ('__global__' == $block && !$this->flagGlobalParsed) {
  513.             $this->parse('__global__');
  514.         }
  515.         // return the parsed block, removing the unknown placeholders if needed
  516.         if (!isset($this->_parsedBlocks[$block])) {
  517.             return '';
  518.  
  519.         } else {
  520.             $ret = $this->_parsedBlocks[$block];
  521.             if ($clear) {
  522.                 unset($this->_parsedBlocks[$block]);
  523.             }
  524.             if ($this->removeUnknownVariables) {
  525.                 $ret = preg_replace($this->removeVariablesRegExp, '', $ret);
  526.             }
  527.             if ($this->_options['preserve_data']) {
  528.                 $ret = str_replace($this->openingDelimiter . '%preserved%' . $this->closingDelimiter, $this->openingDelimiter, $ret);
  529.             }
  530.             return $ret;
  531.         }
  532.     }
  533.  
  534.  
  535.    /**
  536.     * Parses the given block.
  537.     *    
  538.     * @param    string    block name
  539.     * @param    boolean   true if the function is called recursively (do not set this to true yourself!)
  540.     * @param    boolean   true if parsing a "hidden" block (do not set this to true yourself!)
  541.     * @access   public
  542.     * @see      parseCurrentBlock()
  543.     * @throws   PEAR_Error
  544.     */
  545.     function parse($block = '__global__', $flagRecursion = false, $fakeParse = false)
  546.     {
  547.         static $vars;
  548.  
  549.         if (!isset($this->_blocks[$block])) {
  550.             return $this->raiseError($this->errorMessage(SIGMA_BLOCK_NOT_FOUND, $block), SIGMA_BLOCK_NOT_FOUND);
  551.         }
  552.         if ('__global__' == $block) {
  553.             $this->flagGlobalParsed = true;
  554.         }
  555.         if (!isset($this->_parsedBlocks[$block])) {
  556.             $this->_parsedBlocks[$block] = '';
  557.         }
  558.         $outer = $this->_blocks[$block];
  559.  
  560.         if (!$flagRecursion) {
  561.             $vars = array();
  562.         }
  563.         // block is not empty if its local var is substituted
  564.         $empty = true;
  565.         foreach ($this->_blockVariables[$block] as $allowedvar => $v) {
  566.             if (isset($this->_variables[$allowedvar])) {
  567.                 $vars[$this->openingDelimiter . $allowedvar . $this->closingDelimiter] = $this->_variables[$allowedvar];
  568.                 $empty = false;
  569.                 // vital for checking "empty/nonempty" status
  570.                 unset($this->_variables[$allowedvar]);
  571.             }
  572.         }
  573.  
  574.         // processing of the inner blocks
  575.         if (isset($this->_children[$block])) {
  576.             foreach ($this->_children[$block] as $innerblock => $v) {
  577.                 $placeholder = $this->openingDelimiter.'__'.$innerblock.'__'.$this->closingDelimiter;
  578.  
  579.                 if (isset($this->_hiddenBlocks[$innerblock])) {
  580.                     // don't bother actually parsing this inner block; but we _have_
  581.                     // to go through its local vars to prevent problems on next iteration
  582.                     $this->parse($innerblock, true, true);
  583.                     unset($this->_hiddenBlocks[$innerblock]);
  584.                     $outer = str_replace($placeholder, '', $outer);
  585.  
  586.                 } else {
  587.                     $this->parse($innerblock, true, $fakeParse);
  588.                     // block is not empty if its inner block is not empty
  589.                     if ('' != $this->_parsedBlocks[$innerblock]) {
  590.                         $empty = false;
  591.                     }
  592.  
  593.                     $outer = str_replace($placeholder, $this->_parsedBlocks[$innerblock], $outer);
  594.                     $this->_parsedBlocks[$innerblock] = '';
  595.                 }
  596.             }
  597.         }
  598.  
  599.         // add "global" variables to the static array
  600.         foreach ($this->_globalVariables as $allowedvar => $value) {
  601.             if (isset($this->_blockVariables[$block][$allowedvar])) {
  602.                 $vars[$this->openingDelimiter . $allowedvar . $this->closingDelimiter] = $value;
  603.             }
  604.         }
  605.         // if we are inside a hidden block, don't bother
  606.         if (!$fakeParse) {
  607.             if (0 != count($vars) && (!$flagRecursion || !empty($this->_functions[$block]))) {
  608.                 $varKeys     = array_keys($vars);
  609.                 $varValues   = $this->_options['preserve_data']? array_map(array(&$this, '_preserveOpeningDelimiter'), array_values($vars)): array_values($vars);
  610.             }
  611.  
  612.             // check whether the block is considered "empty" and append parsed content if not
  613.             if (!$empty || ('__global__' == $block) || !$this->removeEmptyBlocks || isset($this->_touchedBlocks[$block])) {
  614.                 // perform callbacks
  615.                 if (!empty($this->_functions[$block])) {
  616.                     foreach ($this->_functions[$block] as $id => $data) {
  617.                         $placeholder = $this->openingDelimiter . '__function_' . $id . '__' . $this->closingDelimiter;
  618.                         // do not waste time calling function more than once
  619.                         if (!isset($vars[$placeholder])) {
  620.                             $args         = array();
  621.                             $preserveArgs = isset($this->_callback[$data['name']]['preserveArgs']) && $this->_callback[$data['name']]['preserveArgs'];
  622.                             foreach ($data['args'] as $arg) {
  623.                                 $args[] = (empty($varKeys) || $preserveArgs)? $arg: str_replace($varKeys, $varValues, $arg);
  624.                             }
  625.                             if (isset($this->_callback[$data['name']]['data'])) {
  626.                                 $res = call_user_func_array($this->_callback[$data['name']]['data'], $args);
  627.                             } else {
  628.                                 $res = isset($args[0])? $args[0]: '';
  629.                             }
  630.                             $outer = str_replace($placeholder, $res, $outer);
  631.                             // save the result to variable cache, it can be requested somewhere else
  632.                             $vars[$placeholder] = $res;
  633.                         }
  634.                     }
  635.                 }
  636.                 // substitute variables only on non-recursive call, thus all
  637.                 // variables from all inner blocks get substituted
  638.                 if (!$flagRecursion && !empty($varKeys)) {
  639.                     $outer = str_replace($varKeys, $varValues, $outer);
  640.                 }
  641.  
  642.                 $this->_parsedBlocks[$block] .= $outer;
  643.                 if (isset($this->_touchedBlocks[$block])) {
  644.                     unset($this->_touchedBlocks[$block]);
  645.                 }
  646.             }
  647.         }
  648.         return $empty;
  649.     }
  650.  
  651.  
  652.    /**
  653.     * Sets a variable value.
  654.     * 
  655.     * The function can be used either like setVariable("varname", "value")
  656.     * or with one array $variables["varname"] = "value" given setVariable($variables)
  657.     * 
  658.     * @access public
  659.     * @param  mixed     variable name or array ('varname'=>'value')
  660.     * @param  string    variable value if $variable is not an array
  661.     */
  662.     function setVariable($variable, $value = '')
  663.     {
  664.         if (is_array($variable)) {
  665.             $this->_variables = array_merge($this->_variables, $variable);
  666.         } else {
  667.             $this->_variables[$variable] = $value;
  668.         }
  669.     }
  670.  
  671.  
  672.    /**
  673.     * Sets a global variable value.
  674.     * 
  675.     * @access public
  676.     * @param  mixed     variable name or array ('varname'=>'value')
  677.     * @param  string    variable value if $variable is not an array
  678.     * @see    setVariable()
  679.     */
  680.     function setGlobalVariable($variable, $value = '')
  681.     {
  682.         if (is_array($variable)) {
  683.             $this->_globalVariables = array_merge($this->_globalVariables, $variable);
  684.         } else {
  685.             $this->_globalVariables[$variable] = $value;
  686.         }
  687.     }
  688.  
  689.  
  690.    /**
  691.     * Sets the name of the current block: the block where variables are added
  692.     *
  693.     * @param    string      block name
  694.     * @return   mixed       SIGMA_OK on success, error object on failure
  695.     * @throws   PEAR_Error
  696.     * @access   public
  697.     */
  698.     function setCurrentBlock($block = '__global__')
  699.     {
  700.         if (!isset($this->_blocks[$block])) {
  701.             return $this->raiseError($this->errorMessage(SIGMA_BLOCK_NOT_FOUND, $block), SIGMA_BLOCK_NOT_FOUND);
  702.         }
  703.         $this->currentBlock = $block;
  704.         return SIGMA_OK;
  705.     }
  706.  
  707.  
  708.    /**
  709.     * Parses the current block
  710.     * 
  711.     * @see      parse(), setCurrentBlock()
  712.     * @access   public
  713.     */
  714.     function parseCurrentBlock()
  715.     {
  716.         return $this->parse($this->currentBlock);
  717.     }
  718.  
  719.  
  720.    /**
  721.     * Returns the current block name
  722.     *
  723.     * @return string    block name
  724.     * @access public
  725.     */
  726.     function getCurrentBlock()
  727.     {
  728.         return $this->currentBlock;
  729.     }
  730.  
  731.  
  732.    /**
  733.     * Preserves the block even if empty blocks should be removed.
  734.     *
  735.     * Sometimes you have blocks that should be preserved although they are 
  736.     * empty (no placeholder replaced). Think of a shopping basket. If it's 
  737.     * empty you have to show a message to the user. If it's filled you have
  738.     * to show the contents of the shopping basket. Now where to place the 
  739.     * message that the basket is empty? It's not a good idea to place it 
  740.     * in you application as customers tend to like unecessary minor text
  741.     * changes. Having another template file for an empty basket means that 
  742.     * one fine day the filled and empty basket templates will have different
  743.     * layouts. 
  744.     * 
  745.     * So blocks that do not contain any placeholders but only messages like 
  746.     * "Your shopping basked is empty" are intoduced. Now if there is no 
  747.     * replacement done in such a block the block will be recognized as "empty"
  748.     * and by default ($removeEmptyBlocks = true) be stripped off. To avoid this
  749.     * you can call touchBlock()
  750.     *
  751.     * @param    string      block name
  752.     * @return   mixed       SIGMA_OK on success, error object on failure
  753.     * @throws   PEAR_Error    
  754.     * @access   public
  755.     * @see      $removeEmptyBlocks, $_touchedBlocks
  756.     */
  757.     function touchBlock($block)
  758.     {
  759.         if (!isset($this->_blocks[$block])) {
  760.             return $this->raiseError($this->errorMessage(SIGMA_BLOCK_NOT_FOUND, $block), SIGMA_BLOCK_NOT_FOUND);
  761.         }
  762.         if (isset($this->_hiddenBlocks[$block])) {
  763.             unset($this->_hiddenBlocks[$block]);
  764.         }
  765.         $this->_touchedBlocks[$block] = true;
  766.         return SIGMA_OK;
  767.     }
  768.  
  769.  
  770.    /**
  771.     * Hides the block even if it is not "empty".
  772.     * 
  773.     * Is somewhat an opposite to touchBlock().
  774.     * 
  775.     * Consider a block (a 'edit' link for example) that should be visible to 
  776.     * registered/"special" users only, but its visibility is triggered by 
  777.     * some little 'id' field passed in a large array into setVariable(). You 
  778.     * can either carefully juggle your variables to prevent the block from 
  779.     * appearing (a fragile solution) or simply call hideBlock()
  780.     *
  781.     * @param    string      block name
  782.     * @return   mixed       SIGMA_OK on success, error object on failure
  783.     * @throws   PEAR_Error    
  784.     * @access   public
  785.     */
  786.     function hideBlock($block)
  787.     {
  788.         if (!isset($this->_blocks[$block])) {
  789.             return $this->raiseError($this->errorMessage(SIGMA_BLOCK_NOT_FOUND, $block), SIGMA_BLOCK_NOT_FOUND);
  790.         }
  791.         if (isset($this->_touchedBlocks[$block])) {
  792.             unset($this->_touchedBlocks[$block]);
  793.         }
  794.         $this->_hiddenBlocks[$block] = true;
  795.         return SIGMA_OK;
  796.     }
  797.  
  798.  
  799.    /**
  800.     * Sets the template.
  801.     *
  802.     * You can either load a template file from disk with LoadTemplatefile() or set the
  803.     * template manually using this function.
  804.     * 
  805.     * @access public
  806.     * @param  string      template content
  807.     * @param  boolean     remove unknown/unused variables?
  808.     * @param  boolean     remove empty blocks?
  809.     * @return mixed       SIGMA_OK on success, error object on failure
  810.     * @see    loadTemplatefile()
  811.     */
  812.     function setTemplate($template, $removeUnknownVariables = true, $removeEmptyBlocks = true)
  813.     {
  814.         $this->_resetTemplate($removeUnknownVariables, $removeEmptyBlocks);
  815.         $list = $this->_buildBlocks('<!-- BEGIN __global__ -->'.$template.'<!-- END __global__ -->');
  816.         if (PEAR::isError($list)) {
  817.             return $list;
  818.         }
  819.         $this->_buildBlockVariables();
  820.         return SIGMA_OK;
  821.     }
  822.  
  823.  
  824.    /**
  825.     * Loads a template file.
  826.     * 
  827.     * If caching is on, then it checks whether a "prepared" template exists.
  828.     * If it does, it gets loaded instead of the original, if it does not, then
  829.     * the original gets loaded and prepared and then the prepared version is saved.
  830.     * addBlockfile() and replaceBlockfile() implement quite the same logic.
  831.     *
  832.     * @param    string      filename
  833.     * @param    boolean     remove unknown/unused variables?
  834.     * @param    boolean     remove empty blocks?
  835.     * @access   public
  836.     * @return   mixed       SIGMA_OK on success, error object on failure
  837.     * @see      setTemplate(), $removeUnknownVariables, $removeEmptyBlocks
  838.     */
  839.     function loadTemplateFile($filename, $removeUnknownVariables = true, $removeEmptyBlocks = true)
  840.     {
  841.         if ($this->_isCached($filename)) {
  842.             $this->_resetTemplate($removeUnknownVariables, $removeEmptyBlocks);
  843.             return $this->_getCached($filename);
  844.         }
  845.         $template = $this->_getFile($this->_sourceName($filename));
  846.         if (PEAR::isError($template)) {
  847.             return $template;
  848.         }
  849.         $this->_triggers = array();
  850.         $template = preg_replace($this->includeRegExp, "\$this->_makeTrigger('\\1', '__global__')", $template);
  851.         if (SIGMA_OK !== ($res = $this->setTemplate($template, $removeUnknownVariables, $removeEmptyBlocks))) {
  852.             return $res;
  853.         } else {
  854.             return $this->_writeCache($filename, '__global__');
  855.         }
  856.     }
  857.  
  858.  
  859.    /**
  860.     * Adds a block to the template changing a variable placeholder to a block placeholder.
  861.     *
  862.     * This means that a new block will be integrated into the template in
  863.     * place of a variable placeholder. The variable placeholder will be 
  864.     * removed and the new block will behave in the same way as if it was 
  865.     * inside the original template.
  866.     *
  867.     * The block content must not start with <!-- BEGIN blockname --> and end with
  868.     * <!-- END blockname -->, if it does the error will be thrown.
  869.     * 
  870.     * @param    string    name of the variable placeholder, the name must be unique within the template.
  871.     * @param    string    name of the block to be added
  872.     * @param    string    content of the block
  873.     * @return   mixed     SIGMA_OK on success, error object on failure
  874.     * @throws   PEAR_Error
  875.     * @see      addBlockfile()
  876.     * @access   public
  877.     */
  878.     function addBlock($placeholder, $block, $template)
  879.     {
  880.         if (isset($this->_blocks[$block])) {
  881.             return $this->raiseError($this->errorMessage(SIGMA_BLOCK_EXISTS, $block), SIGMA_BLOCK_EXISTS);
  882.         }
  883.         $parents = $this->_findParentBlocks($placeholder);
  884.         if (0 == count($parents)) {
  885.             return $this->raiseError($this->errorMessage(SIGMA_PLACEHOLDER_NOT_FOUND, $placeholder), SIGMA_PLACEHOLDER_NOT_FOUND);
  886.         } elseif (count($parents) > 1) {
  887.             return $this->raiseError($this->errorMessage(SIGMA_PLACEHOLDER_DUPLICATE, $placeholder), SIGMA_PLACEHOLDER_DUPLICATE);
  888.         }
  889.         
  890.         $template = "<!-- BEGIN $block -->" . $template . "<!-- END $block -->";
  891.         $list     = $this->_buildBlocks($template);
  892.         if (PEAR::isError($list)) {
  893.             return $list;
  894.         }
  895.         $this->_replacePlaceholder($parents[0], $placeholder, $block);
  896.         $this->_buildBlockVariables($block);
  897.         return SIGMA_OK;
  898.     }
  899.     
  900.  
  901.    /**
  902.     * Adds a block taken from a file to the template, changing a variable placeholder 
  903.     * to a block placeholder.
  904.     * 
  905.     * @param      string    name of the variable placeholder
  906.     * @param      string    name of the block to be added
  907.     * @param      string    template file that contains the block
  908.     * @return     mixed     SIGMA_OK on success, error object on failure
  909.     * @throws     PEAR_Error
  910.     * @see        addBlock()
  911.     * @access     public
  912.     */
  913.     function addBlockfile($placeholder, $block, $filename)
  914.     {
  915.         if ($this->_isCached($filename)) {
  916.             return $this->_getCached($filename, $block, $placeholder);
  917.         }
  918.         $template = $this->_getFile($this->_sourceName($filename));
  919.         if (PEAR::isError($template)) {
  920.             return $template;
  921.         }
  922.         $template = preg_replace($this->includeRegExp, "\$this->_makeTrigger('\\1', '{$block}')", $template);
  923.         if (SIGMA_OK !== ($res = $this->addBlock($placeholder, $block, $template))) {
  924.             return $res;
  925.         } else {
  926.             return $this->_writeCache($filename, $block);
  927.         }
  928.     }
  929.  
  930.  
  931.    /**
  932.     * Replaces an existing block with new content.
  933.     * 
  934.     * This function will replace a block of the template and all blocks 
  935.     * contained in it and add a new block instead. This means you can 
  936.     * dynamically change your template.
  937.     * 
  938.     * Sigma analyses the way you've nested blocks and knows which block 
  939.     * belongs into another block. This nesting information helps to make the 
  940.     * API short and simple. Replacing blocks does not only mean that Sigma 
  941.     * has to update the nesting information (relatively time consuming task) 
  942.     * but you have to make sure that you do not get confused due to the 
  943.     * template change yourself.
  944.     * 
  945.     * @param   string    name of a block to replace
  946.     * @param   string    new content
  947.     * @param   boolean   true if the parsed contents of the block should be kept
  948.     * @access  public
  949.     * @see     replaceBlockfile(), addBlock()
  950.     * @return  mixed     SIGMA_OK on success, error object on failure
  951.     * @throws  PEAR_Error
  952.     */
  953.     function replaceBlock($block, $template, $keepContent = false)
  954.     {
  955.         if (!isset($this->_blocks[$block])) {
  956.             return $this->raiseError($this->errorMessage(SIGMA_BLOCK_NOT_FOUND, $block), SIGMA_BLOCK_NOT_FOUND);
  957.         }
  958.         // should not throw a error as we already checked for block existance
  959.         $this->_removeBlockData($block, $keepContent);
  960.         $template = "<!-- BEGIN $block -->" . $template . "<!-- END $block -->";
  961.  
  962.         $list = $this->_buildBlocks($template);
  963.         if (PEAR::isError($list)) {
  964.             return $list;
  965.         }
  966.         // renew the variables list
  967.         $this->_buildBlockVariables($block);
  968.         return SIGMA_OK;
  969.     }
  970.  
  971.  
  972.    /**
  973.     * Replaces an existing block with new content from a file.
  974.     * 
  975.     * @access     public
  976.     * @param      string    name of a block to replace
  977.     * @param      string    template file that contains the block
  978.     * @param      boolean   true if the parsed contents of the block should be kept
  979.     * @return     mixed     SIGMA_OK on success, error object on failure
  980.     * @throws     PEAR_Error
  981.     * @see        replaceBlock(), addBlockfile()
  982.     */
  983.     function replaceBlockfile($block, $filename, $keepContent = false)
  984.     {
  985.         if ($this->_isCached($filename)) {
  986.             if (PEAR::isError($res = $this->_removeBlockData($block, $keepContent))) {
  987.                 return $res;
  988.             } else {
  989.                 return $this->_getCached($filename, $block);
  990.             }
  991.         }
  992.         $template = $this->_getFile($this->_sourceName($filename));
  993.         if (PEAR::isError($template)) {
  994.             return $template;
  995.         }
  996.         $template = preg_replace($this->includeRegExp, "\$this->_makeTrigger('\\1', '{$block}')", $template);
  997.         if (SIGMA_OK !== ($res = $this->replaceBlock($block, $template, $keepContent))) {
  998.             return $res;
  999.         } else {
  1000.             return $this->_writeCache($filename, $block);
  1001.         }
  1002.     }
  1003.  
  1004.  
  1005.    /**
  1006.     * Checks if the block exists in the template
  1007.     *
  1008.     * @param  string  block name
  1009.     * @return bool
  1010.     * @access public
  1011.     */
  1012.     function blockExists($block)
  1013.     {
  1014.         return isset($this->_blocks[$block]);
  1015.     }
  1016.  
  1017.  
  1018.    /**
  1019.     * Returns the name of the (first) block that contains the specified placeholder.
  1020.     *
  1021.     * @param    string  Name of the placeholder you're searching
  1022.     * @param    string  Name of the block to scan. If left out (default) all blocks are scanned.
  1023.     * @return   string  Name of the (first) block that contains the specified placeholder.
  1024.     *                   If the placeholder was not found an empty string is returned.
  1025.     * @access   public
  1026.     * @throws   PEAR_Error
  1027.     */
  1028.     function placeholderExists($placeholder, $block = '')
  1029.     {
  1030.         if ('' != $block && !isset($this->_blocks[$block])) {
  1031.             return $this->raiseError($this->errorMessage(SIGMA_BLOCK_NOT_FOUND, $block), SIGMA_BLOCK_NOT_FOUND);
  1032.         }
  1033.         if ('' != $block) {
  1034.             // if we search in the specific block, we should just check the array
  1035.             return isset($this->_blockVariables[$block][$placeholder])? $block: '';
  1036.         } else {
  1037.             // _findParentBlocks returns an array, we need only the first element
  1038.             $parents = $this->_findParentBlocks($placeholder);
  1039.             return empty($parents)? '': $parents[0];
  1040.         }
  1041.     } // end func placeholderExists
  1042.  
  1043.  
  1044.    /**
  1045.     * Sets a callback function.
  1046.     *
  1047.     * Sigma templates can contain simple function calls. This means that the 
  1048.     * author of the template can add a special placeholder to it: 
  1049.     * func_h1("embedded in h1")
  1050.     * Sigma will parse the template for these placeholders and will allow 
  1051.     * you to define a callback function for them. Callback will be called 
  1052.     * automatically when the block containing such function call is parse()'d.
  1053.     *
  1054.     * Please note that arguments to these template functions can contain 
  1055.     * variable placeholders: func_translate('Hello, {username}'), but not 
  1056.     * blocks or other function calls.
  1057.     * 
  1058.     * This should NOT be used to add logic (except some presentation one) to
  1059.     * the template. If you use a lot of such callbacks and implement business
  1060.     * logic through them, then you're reinventing the wheel. Consider using
  1061.     * XML/XSLT, native PHP or some other template engine.
  1062.     *
  1063.     * <?php
  1064.     * function h_one($arg) {
  1065.     *    return '<h1>' . $arg . '</h1>';
  1066.     * }
  1067.     * ...
  1068.     * $tpl = new HTML_Template_Sigma( ... );
  1069.     * ...
  1070.     * $tpl->setCallbackFunction('h1', 'h_one');
  1071.     * ?>
  1072.     *
  1073.     * template:
  1074.     * func_h1('H1 Headline');
  1075.     *
  1076.     * @param    string    Function name in the template
  1077.     * @param    mixed     A callback: anything that can be passed to call_user_func_array()
  1078.     * @param    bool      If true, then no variable substitution in arguments will take place before function call
  1079.     * @return   mixed     SIGMA_OK on success, error object on failure
  1080.     * @throws   PEAR_Error
  1081.     * @access   public
  1082.     */
  1083.     function setCallbackFunction($tplFunction, $callback, $preserveArgs = false)
  1084.     {
  1085.         if (!is_callable($callback)) {
  1086.             return $this->raiseError($this->errorMessage(SIGMA_INVALID_CALLBACK), SIGMA_INVALID_CALLBACK);
  1087.         }
  1088.         $this->_callback[$tplFunction] = array(
  1089.             'data'         => $callback,
  1090.             'preserveArgs' => $preserveArgs
  1091.         );
  1092.         return SIGMA_OK;
  1093.     } // end func setCallbackFunction
  1094.  
  1095.  
  1096.    /**
  1097.     * Returns a list of blocks within a template.
  1098.     *
  1099.     * If $recursive is false, it returns just a 'flat' array of $parent's
  1100.     * direct subblocks. If $recursive is true, it builds a tree of template
  1101.     * blocks using $parent as root. Tree structure is compatible with 
  1102.     * PEAR::Tree's Memory_Array driver.
  1103.     * 
  1104.     * @param    string  parent block name 
  1105.     * @param    bool    whether to return a tree of child blocks (true) or a 'flat' array (false)
  1106.     * @access   public
  1107.     * @return   array   a list of child blocks
  1108.     * @throws   PEAR_Error
  1109.     */
  1110.     function getBlockList($parent = '__global__', $recursive = false)
  1111.     {
  1112.         if (!isset($this->_blocks[$parent])) {
  1113.             return $this->raiseError($this->errorMessage(SIGMA_BLOCK_NOT_FOUND, $parent), SIGMA_BLOCK_NOT_FOUND);
  1114.         }
  1115.         if (!$recursive) {
  1116.             return isset($this->_children[$parent])? array_keys($this->_children[$parent]): array();
  1117.         } else {
  1118.             $ret = array('name' => $parent);
  1119.             if (!empty($this->_children[$parent])) {
  1120.                 $ret['children'] = array();
  1121.                 foreach (array_keys($this->_children[$parent]) as $child) {
  1122.                     $ret['children'][] = $this->getBlockList($child, true);
  1123.                 }
  1124.             }
  1125.             return $ret;
  1126.         }
  1127.     }
  1128.  
  1129.  
  1130.    /**
  1131.     * Returns a list of placeholders within a block.
  1132.     * 
  1133.     * Only 'normal' placeholders are returned, not auto-created ones.
  1134.     *
  1135.     * @param    string  block name
  1136.     * @access   public
  1137.     * @return   array   a list of placeholders
  1138.     * @throws   PEAR_Error
  1139.     */
  1140.     function getPlaceholderList($block = '__global__')
  1141.     {
  1142.         if (!isset($this->_blocks[$block])) {
  1143.             return $this->raiseError($this->errorMessage(SIGMA_BLOCK_NOT_FOUND, $block), SIGMA_BLOCK_NOT_FOUND);
  1144.         }
  1145.         $ret = array();
  1146.         foreach ($this->_blockVariables[$block] as $var => $v) {
  1147.             if ('__' != substr($var, 0, 2) || '__' != substr($var, -2)) {
  1148.                 $ret[] = $var;
  1149.             }
  1150.         }
  1151.         return $ret;
  1152.     }
  1153.  
  1154.  
  1155.    /**
  1156.     * Clears the variables
  1157.     * 
  1158.     * Global variables are not affected. The method is useful when you add
  1159.     * a lot of variables via setVariable() and are not sure whether all of 
  1160.     * them appear in the block you parse(). If you clear the variables after
  1161.     * parse(), you don't risk them suddenly showing up in other blocks.
  1162.     * 
  1163.     * @access public
  1164.     * @see    setVariable()
  1165.     */
  1166.     function clearVariables()
  1167.     {
  1168.         $this->_variables = array();
  1169.     }
  1170.  
  1171.  
  1172.     //------------------------------------------------------------
  1173.     //
  1174.     // Private methods follow
  1175.     //
  1176.     //------------------------------------------------------------
  1177.  
  1178.  
  1179.    /**
  1180.     * Reads the file and returns its content
  1181.     * 
  1182.     * @param    string    filename
  1183.     * @return   string    file content (or error object)
  1184.     * @access   private
  1185.     */    
  1186.     function _getFile($filename)
  1187.     {
  1188.         if (!($fh = @fopen($filename, 'r'))) {
  1189.             return $this->raiseError($this->errorMessage(SIGMA_TPL_NOT_FOUND, $filename), SIGMA_TPL_NOT_FOUND);
  1190.         }
  1191.         $content = fread($fh, filesize($filename));
  1192.         fclose($fh);
  1193.         return $content;
  1194.     }
  1195.  
  1196.  
  1197.    /**
  1198.     * Recursively builds a list of all variables within a block.
  1199.     *
  1200.     * Also calls _buildFunctionlist() for each block it visits
  1201.     * 
  1202.     * @param    string block name
  1203.     * @see      _buildFunctionlist()
  1204.     * @access   private
  1205.     */
  1206.     function _buildBlockVariables($block = '__global__')
  1207.     {
  1208.         $this->_blockVariables[$block] = array();
  1209.         $this->_functions[$block]      = array();
  1210.         preg_match_all($this->variablesRegExp, $this->_blocks[$block], $regs, PREG_SET_ORDER);
  1211.         foreach ($regs as $match) {
  1212.             $this->_blockVariables[$block][$match[1]] = true;
  1213.             if (!empty($match[3])) {
  1214.                 $funcData = array(
  1215.                     'name' => $match[3],
  1216.                     'args' => array($this->openingDelimiter . $match[1] . $this->closingDelimiter)
  1217.                 );
  1218.                 $funcId   = substr(md5(serialize($funcData)), 0, 10);
  1219.  
  1220.                 // update block info
  1221.                 $this->_blocks[$block] = str_replace($match[0], '{__function_' . $funcId . '__}', $this->_blocks[$block]);
  1222.                 $this->_blockVariables[$block]['__function_' . $funcId . '__'] = true;
  1223.                 $this->_functions[$block][$funcId] = $funcData;
  1224.             }
  1225.         }
  1226.         $this->_buildFunctionlist($block);
  1227.         if (isset($this->_children[$block]) && is_array($this->_children[$block])) {
  1228.             foreach ($this->_children[$block] as $child => $v) {
  1229.                 $this->_buildBlockVariables($child);
  1230.             }
  1231.         }
  1232.     }
  1233.  
  1234.  
  1235.    /**
  1236.     * Recusively builds a list of all blocks within the template.
  1237.     * 
  1238.     * @param    string    template to be scanned
  1239.     * @see      $_blocks
  1240.     * @throws   PEAR_Error
  1241.     * @return   mixed     array of block names on success or error object on failure
  1242.     * @access   private
  1243.     */
  1244.     function _buildBlocks($string)
  1245.     {
  1246.         $blocks = array();
  1247.         if (preg_match_all($this->blockRegExp, $string, $regs, PREG_SET_ORDER)) {
  1248.             foreach ($regs as $k => $match) {
  1249.                 $blockname    = $match[1];
  1250.                 $blockcontent = $match[2];
  1251.                 if (isset($this->_blocks[$blockname]) || isset($blocks[$blockname])) {
  1252.                     return $this->raiseError($this->errorMessage(SIGMA_BLOCK_DUPLICATE, $blockname), SIGMA_BLOCK_DUPLICATE);
  1253.                 }
  1254.                 $this->_blocks[$blockname] = $blockcontent;
  1255.                 $blocks[$blockname] = true;
  1256.                 $inner              = $this->_buildBlocks($blockcontent);
  1257.                 if (PEAR::isError($inner)) {
  1258.                     return $inner;
  1259.                 }
  1260.                 foreach ($inner as $name => $v) {
  1261.                     $pattern     = sprintf('@<!--\s+BEGIN\s+%s\s+-->(.*)<!--\s+END\s+%s\s+-->@sm', $name, $name);
  1262.                     $replacement = $this->openingDelimiter.'__'.$name.'__'.$this->closingDelimiter;
  1263.                     $this->_blocks[$blockname]          = preg_replace($pattern, $replacement, $this->_blocks[$blockname]);
  1264.                     $this->_children[$blockname][$name] = true;
  1265.                 }
  1266.             }
  1267.         }
  1268.         return $blocks;
  1269.     }
  1270.  
  1271.  
  1272.    /**
  1273.     * Resets the object's properties, used before processing a new template
  1274.     *
  1275.     * @access   private
  1276.     * @param    boolean     remove unknown/unused variables?
  1277.     * @param    boolean     remove empty blocks?
  1278.     * @see      setTemplate(), loadTemplateFile()
  1279.     * @access   private
  1280.     */
  1281.     function _resetTemplate($removeUnknownVariables = true, $removeEmptyBlocks = true)
  1282.     {
  1283.         $this->removeUnknownVariables = $removeUnknownVariables;
  1284.         $this->removeEmptyBlocks      = $removeEmptyBlocks;
  1285.         $this->currentBlock           = '__global__';
  1286.         $this->_variables             = array();
  1287.         $this->_blocks                = array();
  1288.         $this->_children              = array();
  1289.         $this->_parsedBlocks          = array();
  1290.         $this->_touchedBlocks         = array();
  1291.         $this->_functions             = array();
  1292.         $this->flagGlobalParsed       = false;
  1293.     } // _resetTemplate
  1294.  
  1295.  
  1296.    /**
  1297.     * Checks whether we have a "prepared" template cached.
  1298.     * 
  1299.     * If we do not do caching, always returns false
  1300.     * 
  1301.     * @access private
  1302.     * @param  string source filename
  1303.     * @return bool yes/no
  1304.     * @see loadTemplatefile(), addBlockfile(), replaceBlockfile()
  1305.     */
  1306.     function _isCached($filename)
  1307.     {
  1308.         if (null === $this->_cacheRoot) {
  1309.             return false;
  1310.         }
  1311.         $cachedName = $this->_cachedName($filename);
  1312.         $sourceName = $this->_sourceName($filename);
  1313.         // if $sourceName does not exist, error will be thrown later
  1314.         $sourceTime = @filemtime($sourceName);
  1315.         if ((false !== $sourceTime) && @file_exists($cachedName) && (filemtime($cachedName) > $sourceTime)) {
  1316.             return true;
  1317.         } else {
  1318.             return false;
  1319.         }
  1320.     } // _isCached
  1321.  
  1322.  
  1323.    /**
  1324.     * Loads a "prepared" template file
  1325.     *
  1326.     * @access   private
  1327.     * @param    string  filename
  1328.     * @param    string  block name
  1329.     * @param    string  variable placeholder to replace by a block
  1330.     * @return   mixed   SIGMA_OK on success, error object on failure
  1331.     * @see loadTemplatefile(), addBlockfile(), replaceBlockfile()
  1332.     */
  1333.     function _getCached($filename, $block = '__global__', $placeholder = '')
  1334.     {
  1335.         // the same checks are done in addBlock()
  1336.         if (!empty($placeholder)) {
  1337.             if (isset($this->_blocks[$block])) {
  1338.                 return $this->raiseError($this->errorMessage(SIGMA_BLOCK_EXISTS, $block), SIGMA_BLOCK_EXISTS);
  1339.             }
  1340.             $parents = $this->_findParentBlocks($placeholder);
  1341.             if (0 == count($parents)) {
  1342.                 return $this->raiseError($this->errorMessage(SIGMA_PLACEHOLDER_NOT_FOUND, $placeholder), SIGMA_PLACEHOLDER_NOT_FOUND);
  1343.             } elseif (count($parents) > 1) {
  1344.                 return $this->raiseError($this->errorMessage(SIGMA_PLACEHOLDER_DUPLICATE, $placeholder), SIGMA_PLACEHOLDER_DUPLICATE);
  1345.             }
  1346.         }
  1347.         $content = $this->_getFile($this->_cachedName($filename));
  1348.         if (PEAR::isError($content)) {
  1349.             return $content;
  1350.         }
  1351.         $cache = unserialize($content);
  1352.         if ('__global__' != $block) {
  1353.             $this->_blocks[$block]         = $cache['blocks']['__global__'];
  1354.             $this->_blockVariables[$block] = $cache['variables']['__global__'];
  1355.             $this->_children[$block]       = $cache['children']['__global__'];
  1356.             $this->_functions[$block]      = $cache['functions']['__global__'];
  1357.             unset($cache['blocks']['__global__'], $cache['variables']['__global__'], $cache['children']['__global__'], $cache['functions']['__global__']);
  1358.         }
  1359.         $this->_blocks         = array_merge($this->_blocks, $cache['blocks']);
  1360.         $this->_blockVariables = array_merge($this->_blockVariables, $cache['variables']);
  1361.         $this->_children       = array_merge($this->_children, $cache['children']);
  1362.         $this->_functions      = array_merge($this->_functions, $cache['functions']);
  1363.  
  1364.         // the same thing gets done in addBlockfile()
  1365.         if (!empty($placeholder)) {
  1366.             $this->_replacePlaceholder($parents[0], $placeholder, $block);
  1367.         }
  1368.         // pull the triggers, if any
  1369.         if (isset($cache['triggers'])) {
  1370.             return $this->_pullTriggers($cache['triggers']);
  1371.         }
  1372.         return SIGMA_OK;
  1373.     } // _getCached
  1374.  
  1375.  
  1376.    /**
  1377.     * Returns a full name of a "prepared" template file
  1378.     * 
  1379.     * @access private
  1380.     * @param string  source filename, relative to root directory
  1381.     * @return string filename
  1382.     */
  1383.     function _cachedName($filename)
  1384.     {
  1385.         if ('/' == $filename{0} && '/' == substr($this->_cacheRoot, -1)) {
  1386.             $filename = substr($filename, 1);
  1387.         }
  1388.         $filename = str_replace('/', '__', $filename);
  1389.         return $this->_cacheRoot. $filename. '.it';
  1390.     } // _cachedName
  1391.  
  1392.  
  1393.    /**
  1394.     * Returns a full name of a "source" template file
  1395.     *
  1396.     * @param string   source filename, relative to root directory
  1397.     * @access private
  1398.     * @return string
  1399.     */
  1400.     function _sourceName($filename)
  1401.     {
  1402.         if ('/' == $filename{0} && '/' == substr($this->fileRoot, -1)) {
  1403.             $filename = substr($filename, 1);
  1404.         }
  1405.         return $this->fileRoot . $filename;
  1406.     } // _sourceName
  1407.  
  1408.  
  1409.    /**
  1410.     * Writes a prepared template file.
  1411.     * 
  1412.     * Even if NO caching is going on, this method has a side effect: it calls 
  1413.     * the _pullTriggers() method and thus loads all files added via <!-- INCLUDE -->
  1414.     *
  1415.     * @access private
  1416.     * @param string   source filename, relative to root directory
  1417.     * @param string   name of the block to save into file
  1418.     * @return mixed   SIGMA_OK on success, error object on failure
  1419.     */
  1420.     function _writeCache($filename, $block)
  1421.     {
  1422.         // do not save anything if no cache dir, but do pull triggers
  1423.         if (null !== $this->_cacheRoot) {
  1424.             $cache = array(
  1425.                 'blocks'    => array(),
  1426.                 'variables' => array(),
  1427.                 'children'  => array(),
  1428.                 'functions' => array()
  1429.             );
  1430.             $cachedName = $this->_cachedName($filename);
  1431.             $this->_buildCache($cache, $block);
  1432.             if ('__global__' != $block) {
  1433.                 foreach (array_keys($cache) as $k) {
  1434.                     $cache[$k]['__global__'] = $cache[$k][$block];
  1435.                     unset($cache[$k][$block]);
  1436.                 }
  1437.             }
  1438.             if (isset($this->_triggers[$block])) {
  1439.                 $cache['triggers'] = $this->_triggers[$block];
  1440.             }
  1441.             if (!($fh = @fopen($cachedName, 'w'))) {
  1442.                 return $this->raiseError($this->errorMessage(SIGMA_CACHE_ERROR, $cachedName), SIGMA_CACHE_ERROR);
  1443.             }
  1444.             fwrite($fh, serialize($cache));
  1445.             fclose($fh);
  1446.         }
  1447.         // now pull triggers
  1448.         if (isset($this->_triggers[$block])) {
  1449.             if (SIGMA_OK !== ($res = $this->_pullTriggers($this->_triggers[$block]))) {
  1450.                 return $res;
  1451.             }
  1452.             unset($this->_triggers[$block]);
  1453.         }
  1454.         return SIGMA_OK;
  1455.     } // _writeCache
  1456.  
  1457.  
  1458.    /**
  1459.     * Builds an array of template data to be saved in prepared template file
  1460.     *
  1461.     * @access private
  1462.     * @param array   template data
  1463.     * @param string  block to add to the array
  1464.     */
  1465.     function _buildCache(&$cache, $block)
  1466.     {
  1467.         if (!$this->_options['trim_on_save']) {
  1468.             $cache['blocks'][$block] = $this->_blocks[$block];
  1469.         } else {
  1470.             $cache['blocks'][$block] = preg_replace(
  1471.                                          array('/^\\s+/m', '/\\s+$/m', '/(\\r?\\n)+/'),
  1472.                                          array('', '', "\n"),
  1473.                                          $this->_blocks[$block]
  1474.                                        );
  1475.         }
  1476.         $cache['variables'][$block] = $this->_blockVariables[$block];
  1477.         $cache['functions'][$block] = isset($this->_functions[$block])? $this->_functions[$block]: array();
  1478.         if (!isset($this->_children[$block])) {
  1479.             $cache['children'][$block] = array();
  1480.         } else {
  1481.             $cache['children'][$block] = $this->_children[$block];
  1482.             foreach (array_keys($this->_children[$block]) as $child) {
  1483.                 $this->_buildCache($cache, $child);
  1484.             }
  1485.         }
  1486.     }
  1487.  
  1488.  
  1489.    /**
  1490.     * Recursively removes all data belonging to a block
  1491.     * 
  1492.     * @param    string    block name
  1493.     * @param    boolean   true if the parsed contents of the block should be kept
  1494.     * @return   mixed     SIGMA_OK on success, error object on failure
  1495.     * @see      replaceBlock(), replaceBlockfile()
  1496.     * @access   private
  1497.     */
  1498.     function _removeBlockData($block, $keepContent = false)
  1499.     {
  1500.         if (!isset($this->_blocks[$block])) {
  1501.             return $this->raiseError($this->errorMessage(SIGMA_BLOCK_NOT_FOUND, $block), SIGMA_BLOCK_NOT_FOUND);
  1502.         }
  1503.         if (!empty($this->_children[$block])) {
  1504.             foreach (array_keys($this->_children[$block]) as $child) {
  1505.                 $this->_removeBlockData($child, false);
  1506.             }
  1507.             unset($this->_children[$block]);
  1508.         }
  1509.         unset($this->_blocks[$block]);
  1510.         unset($this->_blockVariables[$block]);
  1511.         unset($this->_hiddenBlocks[$block]);
  1512.         unset($this->_touchedBlocks[$block]);
  1513.         unset($this->_functions[$block]);
  1514.         if (!$keepContent) {
  1515.             unset($this->_parsedBlocks[$block]);
  1516.         }
  1517.         return SIGMA_OK;
  1518.     }
  1519.  
  1520.  
  1521.    /**
  1522.     * Returns the names of the blocks where the variable placeholder appears
  1523.     *
  1524.     * @param    string    variable name
  1525.     * @return    array    block names
  1526.     * @see addBlock(), addBlockfile(), placeholderExists()
  1527.     * @access   private
  1528.     */
  1529.     function _findParentBlocks($variable)
  1530.     {
  1531.         $parents = array();
  1532.         foreach ($this->_blockVariables as $blockname => $varnames) {
  1533.             if (!empty($varnames[$variable])) {
  1534.                 $parents[] = $blockname;
  1535.             }
  1536.         }
  1537.         return $parents;
  1538.     }
  1539.  
  1540.  
  1541.    /**
  1542.     * Replaces a variable placeholder by a block placeholder.
  1543.     * 
  1544.     * Of course, it also updates the necessary arrays
  1545.     * 
  1546.     * @param    string  name of the block containing the placeholder
  1547.     * @param    string  variable name
  1548.     * @param    string  block name
  1549.     * @access   private
  1550.     */
  1551.     function _replacePlaceholder($parent, $placeholder, $block)
  1552.     {
  1553.         $this->_children[$parent][$block] = true;
  1554.         $this->_blockVariables[$parent]['__'.$block.'__'] = true;
  1555.         $this->_blocks[$parent]    = str_replace($this->openingDelimiter.$placeholder.$this->closingDelimiter,
  1556.                                                         $this->openingDelimiter.'__'.$block.'__'.$this->closingDelimiter,
  1557.                                                         $this->_blocks[$parent] );
  1558.         unset($this->_blockVariables[$parent][$placeholder]);
  1559.     }
  1560.  
  1561.  
  1562.    /**
  1563.     * Generates a placeholder to replace an <!-- INCLUDE filename --> statement
  1564.     * 
  1565.     * @access   private
  1566.     * @param    string  filename
  1567.     * @param    string  current block name
  1568.     * @return   string  a placeholder
  1569.     */
  1570.     function _makeTrigger($filename, $block)
  1571.     {
  1572.         $name = 'trigger_' . substr(md5($filename . ' ' . uniqid($block)), 0, 10);
  1573.         $this->_triggers[$block][$name] = $filename;
  1574.         return $this->openingDelimiter . $name . $this->closingDelimiter;
  1575.     }
  1576.  
  1577.  
  1578.    /**
  1579.     * Replaces the "trigger" placeholders by the matching file contents.
  1580.     * 
  1581.     * @see _makeTrigger(), addBlockfile()
  1582.     * @param    array   array ('trigger placeholder' => 'filename')
  1583.     * @return   mixed   SIGMA_OK on success, error object on failure
  1584.     * @access   private
  1585.     */
  1586.     function _pullTriggers($triggers)
  1587.     {
  1588.         foreach ($triggers as $placeholder => $filename) {
  1589.             if (SIGMA_OK !== ($res = $this->addBlockfile($placeholder, $placeholder, $filename))) {
  1590.                 return $res;
  1591.             }
  1592.             // we actually do not need the resultant block...
  1593.             $parents = $this->_findParentBlocks('__' . $placeholder . '__');
  1594.             // merge current block's children and variables with the parent's ones
  1595.             if (isset($this->_children[$placeholder])) {
  1596.                 $this->_children[$parents[0]] = array_merge($this->_children[$parents[0]], $this->_children[$placeholder]);
  1597.             }
  1598.             $this->_blockVariables[$parents[0]] = array_merge($this->_blockVariables[$parents[0]], $this->_blockVariables[$placeholder]);
  1599.             if (isset($this->_functions[$placeholder])) {
  1600.                 $this->_functions[$parents[0]] = array_merge($this->_functions[$parents[0]], $this->_functions[$placeholder]);
  1601.             }
  1602.             // substitute the block's contents into parent's
  1603.             $this->_blocks[$parents[0]] = str_replace(
  1604.                                             $this->openingDelimiter . '__' . $placeholder . '__' . $this->closingDelimiter, 
  1605.                                             $this->_blocks[$placeholder], 
  1606.                                             $this->_blocks[$parents[0]]
  1607.                                           );
  1608.             // remove the stuff that is no more needed
  1609.             unset($this->_blocks[$placeholder], $this->_blockVariables[$placeholder], $this->_children[$placeholder], $this->_functions[$placeholder]);
  1610.             unset($this->_children[$parents[0]][$placeholder], $this->_blockVariables[$parents[0]]['__' . $placeholder . '__']);
  1611.         }
  1612.         return SIGMA_OK;
  1613.     }
  1614.  
  1615.  
  1616.    /**
  1617.     * Builds a list of functions in a block.
  1618.     *
  1619.     * @access   private
  1620.     * @param    string  Block name
  1621.     * @see _buildBlockVariables()
  1622.     */
  1623.     function _buildFunctionlist($block)
  1624.     {
  1625.         $template = $this->_blocks[$block];
  1626.  
  1627.         while (preg_match($this->functionRegExp, $template, $regs)) {
  1628.  
  1629.             $template = substr($template, strpos($template, $regs[0]) + strlen($regs[0]));
  1630.             $head     = $this->_getToken($template, ')');
  1631.             $funcText = $regs[0] . $head . ')';
  1632.             $funcData = array(
  1633.                 'name' => $regs[1],
  1634.                 'args' => array()
  1635.             );
  1636.             // build function arguments
  1637.             while (('' != $head) && ('' != trim($arg = $this->_getToken($head, ',')))) {
  1638.                 $arg2 = trim($arg);
  1639.                 $funcData['args'][] = ('"' == $arg2{0} || "'" == $arg2{0}) ? substr($arg2, 1, -1) : $arg2;
  1640.                 if ($arg == $head) {
  1641.                     break;
  1642.                 }
  1643.                 $head = substr($head, strlen($arg) + 1);
  1644.             }
  1645.             $funcId   = substr(md5(serialize($funcData)), 0, 10);
  1646.             $template = str_replace($funcText, '{__function_' . $funcId . '__}', $template);
  1647.  
  1648.             // update block info
  1649.             $this->_blocks[$block] = str_replace($funcText, '{__function_' . $funcId . '__}', $this->_blocks[$block]);
  1650.             $this->_blockVariables[$block]['__function_' . $funcId . '__'] = true;
  1651.             $this->_functions[$block][$funcId] = $funcData;
  1652.         }
  1653.     } // end func _buildFunctionlist
  1654.  
  1655.  
  1656.    /**
  1657.     * Returns a part of string up to a delimiter.
  1658.     * 
  1659.     * It should handle strings enclosed in single and double quotes, 
  1660.     * thus the need for a non-trivial function
  1661.     * 
  1662.     * @param    string  a string from which to extract
  1663.     * @param    mixed   a delimiter or an array of ('delimiter' => true)
  1664.     * @return   string  an extracted string
  1665.     * @access   private
  1666.     */
  1667.     function _getToken($code, $delimiter)
  1668.     {
  1669.         if (!is_array($delimiter)) {
  1670.             $delimiter = array( $delimiter => true );
  1671.         }
  1672.         if ('' == $code || isset($delimiter[$code{0}])) {
  1673.             return '';
  1674.         }
  1675.  
  1676.         $len         = strlen($code);
  1677.         $enclosed    = false;
  1678.         $enclosed_by = '';
  1679.  
  1680.         for ($i = 0; $i < $len; $i++) {
  1681.             $char = $code{$i};
  1682.  
  1683.             if (('"' == $char || "'" == $char) && 
  1684.                 ($char == $enclosed_by || '' == $enclosed_by) && 
  1685.                 (0 == $i || ($i > 0 && '\\' != $code{$i - 1}))) 
  1686.             {
  1687.                 $enclosed_by = $enclosed? '': $char;
  1688.                 $enclosed    = !$enclosed;
  1689.             }
  1690.             if (!$enclosed && isset($delimiter[$char])) {
  1691.                 break;
  1692.             }
  1693.         }
  1694.         return substr($code, 0, $i);
  1695.     } // end func _getToken
  1696.  
  1697.  
  1698.    /**
  1699.     * Replaces an opening delimiter by a special string.
  1700.     * 
  1701.     * Used to implement $_options['preserve_data'] logic
  1702.     * 
  1703.     * @access   private
  1704.     * @param string
  1705.     * @return string
  1706.     */
  1707.     function _preserveOpeningDelimiter($str)
  1708.     {
  1709.         return (false === strpos($str, $this->openingDelimiter))? 
  1710.                 $str:
  1711.                 str_replace($this->openingDelimiter, $this->openingDelimiter . '%preserved%' . $this->closingDelimiter, $str);
  1712.     }
  1713.  
  1714.  
  1715.    /**
  1716.     * Quotes the string so that it can be used in Javascript string constants
  1717.     *
  1718.     * @access private
  1719.     * @param  string
  1720.     * @return string
  1721.     */
  1722.     function _jsEscape($value)
  1723.     {
  1724.         return strtr($value, array(
  1725.                     "\r" => '\r', "'"  => "\\'", "\n" => '\n', 
  1726.                     '"'  => '\"', "\t" => '\t',  '\\' => '\\\\'
  1727.                ));
  1728.     }
  1729. }
  1730. ?>
  1731.